home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UScripting.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  17.5 KB  |  569 lines  |  [TEXT/MPS ]
  1. // UScripting.h
  2. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __USCRIPTING__
  5. #define __USCRIPTING__
  6.  
  7. // MacApp
  8.  
  9. #ifndef __UAPPLEEVENTS__
  10. #include "UAppleEvents.h"
  11. #endif
  12.  
  13. #ifndef __UCLASSDESC__
  14. #include "UClassDesc.h"
  15. #endif
  16.  
  17. #ifndef __ULIST__
  18. #include "UList.h"
  19. #endif
  20.  
  21. #ifndef __UOBJECT__
  22. #include "UObject.h"
  23. #endif
  24.  
  25. #ifndef __USCRIPTABLEOBJECT__
  26. #include "UScriptableObject.h"
  27. #endif
  28.  
  29. // Toolbox
  30.  
  31.  
  32. //----------------------------------------------------------------------------------------
  33. // Forward and external class declarations. 
  34. //----------------------------------------------------------------------------------------
  35.  
  36. class TCommand;
  37. class TEventList;
  38.  
  39. //----------------------------------------------------------------------------------------
  40. // Structures
  41. //----------------------------------------------------------------------------------------
  42.  
  43. struct MAEventTableRec    // format of an entry in our dispatch table resource (type 'aedt')
  44. {
  45.     OSType theClass;
  46.     OSType theID;
  47.     long theValue;
  48. };
  49. //----------------------------------------------------------------------------------------
  50. // TOSADispatcher
  51. //----------------------------------------------------------------------------------------
  52.  
  53. class TOSADispatcher : public TObject
  54. {
  55.     MA_DECLARE_CLASS;
  56.     
  57.     // This object manages the resolution and dispatching of incoming and outgoing
  58.     // object model apple events.
  59.         
  60. public:
  61.  
  62.     static TOSADispatcher* fgDispatcher;
  63.  
  64.     //------------------------------------------------------------------------------------
  65.     // Initialization: creates one and one instance of the scripting dispatcher
  66.     //------------------------------------------------------------------------------------
  67.         
  68.     static void InitUScripting(MA_ClassReference classDesc);
  69.         // Initialize the scripting unit. Call this function to create a global
  70.         // instance of TScriptEventDispatcher or one of its subclasses, and to
  71.         // install events supported in Apple Event dispatch table resources. 
  72.     
  73. protected:
  74.     
  75.     TOSADispatcher();
  76.         // Creation should be done only through InitUScripting. 
  77.     
  78.     void IOSADispatcher();
  79.         // Initialization should be done only through InitUScripting. 
  80.     
  81. public:
  82.     
  83.     virtual ~TOSADispatcher();
  84.     
  85.     inline void SetDefaultTarget(MDefaultScriptableObject* defaultTarget);
  86.     
  87.     inline MDefaultScriptableObject* GetDefaultTarget();
  88.     
  89.     inline long GetDispatchLevel() const { return fDispatchLevel; }
  90.     
  91.     inline void SetAEResolveFlags(const short newFlags);
  92.     
  93.     virtual MScriptableObject* ResolveObjectSpecifier(CAEDesc& objectDesc);
  94.     
  95.     virtual CommandNumber GetAppleEventCommandNumber(AEEventClass eventClass, AEEventID eventID);
  96.  
  97.     virtual TList* GetTemporaryTokens(void);
  98.         // return the current list of temporary tokens
  99.         
  100.     virtual void AddTemporaryToken(TObject* tempToken);
  101.         // Add the tempToken to a list whose contents will be disposed of after the
  102.         // Apple Event has been handled.
  103.  
  104.     virtual void FreeTemporaryTokens();
  105.         // Frees all the objects in the temp token disposal list.
  106.             
  107.     virtual void PostPendingReplyCommand(TCommand* command);
  108.         // add a client command that is waiting for a reply to a local command
  109.         // queue.
  110.     
  111. #if qAttachable
  112.     virtual void ScriptAttached();
  113.         // Call when you have an attached OSA script that wants to receive
  114.         // pre-dispatched Apple Events. 
  115.  
  116.     virtual void ScriptDetached();
  117.         // Call when you have an OSA script is detached and no longer wants
  118.         // to receive pre-dispatched Apple Events. 
  119. #endif
  120.  
  121. protected:
  122.     
  123.     virtual void InstallDispatchHandlers();
  124.     
  125. #if qAttachable
  126.     virtual void InstallPreDispatchHandler();
  127.  
  128.     virtual void RemovePreDispatchHandler();
  129. #endif
  130.  
  131.     virtual void InstallObjectCallbacks();
  132.     
  133.     //------------------------------------------------------------------------------------
  134.     // Dispatch Methods:
  135.     //------------------------------------------------------------------------------------
  136.  
  137. #if qAttachable
  138.     virtual OSErr PreDispatchHandler(CommandNumber aCommandNumber, TAppleEvent* message, 
  139.                         TAppleEvent* reply);
  140. #endif
  141.  
  142.     virtual OSErr DispatchHandler(CommandNumber aCommandNumber, TAppleEvent* message, 
  143.                         TAppleEvent* reply);
  144.                         
  145.     virtual void ReportDispatchError(AppleEvent* message, AppleEvent* reply,
  146.                         OSErr dispatchErr, long dispatchErrMessage);
  147.                         
  148.     virtual MScriptableObject* GetTargetObject(CommandNumber aCommandNumber, 
  149.                         TAppleEvent* appleEvent);
  150.  
  151.     //------------------------------------------------------------------------------------
  152.     // Object Support Library (OSL) Callbacks :
  153.     //------------------------------------------------------------------------------------
  154.     
  155.     virtual void ObjectAccessor(DescType desiredClass,
  156.                                 CAEDesc& container,
  157.                                 DescType containerClass,
  158.                                 DescType form,
  159.                                 CAEDesc& selectionData,
  160.                                 CAEDesc& value,
  161.                                 long accessorRefcon);
  162.  
  163.     virtual long CountObjects(DescType desiredType,
  164.                               DescType containerClass,
  165.                               CAEDesc& container);
  166.  
  167.     virtual Boolean CompareObjects(DescType whichOperation,
  168.                                    CAEDesc& targetDesc,
  169.                                    CAEDesc& thingToCompare);
  170.  
  171.     virtual void DisposeToken(CAEDesc& unneededToken);
  172.     
  173.     virtual void GetMarkToken(CAEDesc& theContainerToken,
  174.                               DescType containerClass,
  175.                               CAEDesc& result);
  176.                                                                 
  177.     virtual void MarkObject(CAEDesc& theToken,
  178.                             CAEDesc& markingListToken,
  179.                             long index);
  180.  
  181.  
  182.     virtual void AdjustMarks(long newStart,
  183.                              long newStop,
  184.                              CAEDesc& markToken);    
  185.     
  186.     virtual void MatchReplyToPending(TAppleEvent* reply);
  187.         // match the supplied reply with a TClientCommand in the fPendingReplyList.
  188.         
  189.     //------------------------------------------------------------------------------------
  190.     // Callback glue: glues static callbacks to matching virtual member functions.
  191.     //------------------------------------------------------------------------------------
  192.     
  193. #if qAttachable
  194.     static pascal OSErr PreDispatchHandlerGlue(AppleEvent* message,
  195.                                                 AppleEvent* reply,
  196.                                                 long info);
  197. #endif
  198.     
  199.     static pascal OSErr DispatchHandlerGlue(AppleEvent* message,
  200.                                             AppleEvent* reply,
  201.                                             long info);
  202.     
  203.     static pascal OSErr ObjectAccessorGlue(DescType desiredClass, 
  204.                                             AEDesc* container, 
  205.                                             DescType containerClass, 
  206.                                             DescType form, 
  207.                                             AEDesc* selectionData, 
  208.                                             AEDesc* value,
  209.                                             long accessorRefcon);
  210.  
  211.     static pascal OSErr CountObjectsGlue(DescType desiredType,
  212.                                             DescType containerClass,
  213.                                             AEDesc* container,
  214.                                             long* result);
  215.                                             
  216.     static pascal OSErr CompareObjectsGlue(DescType whichOperation,
  217.                                                 AEDesc* obj1,
  218.                                                 AEDesc* obj2,
  219.                                                 Boolean* result);
  220.                                                 
  221.     static pascal OSErr DisposeTokenGlue(AEDesc* unneededToken);
  222.  
  223.     static pascal OSErr GetMarkTokenGlue(AEDesc* containerToken,
  224.                                             DescType containerClass,
  225.                                             AEDesc* result);
  226.  
  227.     static pascal OSErr MarkObjectGlue(AEDesc* dToken,
  228.                                         AEDesc* markToken,
  229.                                         long index);
  230.                                         
  231.      static pascal OSErr AdjustMarksGlue(long newStart,
  232.                                         long newStop,
  233.                                         AEDesc* markToken);
  234.                                             
  235. protected:
  236.     
  237.     MDefaultScriptableObject*    fDefaultTarget;        // When no other target is specified. 
  238.     
  239.     TList*                fTemporaryTokens;            // token objects to be thrown out after
  240.                                                     // an event has been handled.
  241.     
  242.     long                fDispatchLevel;
  243.     
  244.     short                fAEResolveFlags;            // callback flags passed to AEResolve
  245.  
  246.     TEventList*            fPendingReplyList;            // Commands that are waiting to be posted
  247.                                                     // pending the receipt of their reply.
  248.                                                     // Commands that are sent with QueueReply
  249.                                                     // end up in this queue    
  250.     
  251.     AEEventHandlerUPP     fDispatchUPP;
  252. #if qAttachable
  253.     long                 fAttachedScripts;            // Count of the number of attached
  254.                                                     // scripts expecting pre-dispatching. 
  255.     AEEventHandlerUPP    fPreDispatchUPP;
  256. #endif
  257.     OSLAccessorUPP        fAccessorUPP;
  258.     OSLCompareUPP        fCompareUPP;
  259.     OSLCountUPP            fCountUPP;
  260.     OSLDisposeTokenUPP    fDisposeTokenUPP;
  261.     OSLGetMarkTokenUPP    fGetMarkTokenUPP;
  262.     OSLMarkUPP            fMarkUPP;
  263.     OSLAdjustMarksUPP    fAdjustMarksUPP;
  264. };
  265.  
  266.  
  267. //----------------------------------------------------------------------------------------
  268. // TScriptableObjectList
  269. //----------------------------------------------------------------------------------------
  270.  
  271. const DescType cScriptableObjectList = 'olst';
  272.  
  273. class TScriptableObjectList : public TList, public MScriptableObject
  274. {
  275.  
  276.     MA_DECLARE_CLASS;
  277.  
  278.     // This represents a list of objects that are marked by the OSL. When the
  279.     // OSL gets a complex object specifier it determines which objects should
  280.     // be marked for action. The marked objects are kept in a TScriptableObjectList.
  281.  
  282. public:
  283.  
  284.     MScriptableObject* fContainer;                        // The object that contains the objects in this list.
  285.  
  286.     TScriptableObjectList();
  287.     virtual ~TScriptableObjectList();
  288.         // Destructor
  289.  
  290.     virtual void IScriptableObjectList(MScriptableObject* itsContainer);
  291.  
  292.     virtual void DoAECountElements(TAppleEvent* message,
  293.                                    TAppleEvent* reply);
  294.  
  295.     virtual void DoScriptCommand(CommandNumber aCommandNumber,
  296.                                 TAppleEvent* message,
  297.                                 TAppleEvent* reply);
  298.         // Calls DoScriptCommand for each object in the list.
  299.  
  300.     virtual void InsertMarkedObject(MScriptableObject* theObjectMarked);
  301.         // Adds an object to be marked.
  302.  
  303.     virtual void AdjustMarks(long newStart,
  304.                              long newStop);
  305.         // Changes the range of objects to be marked.
  306.  
  307.     virtual MScriptableObject* GetObjectsContainer();
  308.         // Returns fContainer.
  309.  
  310.     virtual Boolean IsPropertyList();
  311.         // Is this a list of property descriptors?
  312.  
  313.     virtual MScriptableObject* GetContainedObject(DescType desiredType,
  314.                                                   DescType selectionForm,
  315.                                                   const CAEDesc& selectionData);
  316.         // Returns a list of objects contained within the objects in this list.
  317.  
  318.     virtual long CountContainedObjects(DescType desiredType);
  319.         // Adds up CountContainedObjects for all objects in the list.
  320.  
  321. };
  322.  
  323. //----------------------------------------------------------------------------------------
  324. // TSetPropertyCommand
  325. //----------------------------------------------------------------------------------------
  326.  
  327. #ifndef __UCOMMAND__
  328. #include "UCommand.h"
  329. #endif
  330.  
  331. class TSetPropertyCommand : public TCommand
  332. {
  333.  
  334.     MA_DECLARE_CLASS;
  335.  
  336.     // When MacApp recieves a SetData Apple Event for a property it will create a
  337.     // TSetPropertyCommand to actually do the property setting. It will call the 
  338.     // object whose property is being set to get specifics for the command.
  339.     // If you want to provide your own command number so the undo menu looks right,
  340.     // override the object's GetSetPropertyInfo method to supply your own command
  341.     // information.
  342.     // TSetPropertyCommand implements undo by first calling GetObjectProperty for
  343.     // each affected object, then restoring this value on undo.
  344.  
  345. public:
  346.  
  347.     TList* fObjectsToSet;
  348.     TList* fObjectsToFree;
  349.     DescType fProperty;
  350.     CAEDesc fOldPropData;
  351.     CAEDesc fNewPropData;
  352.  
  353.     TSetPropertyCommand();
  354.  
  355.     virtual void ISetPropertyCommand(DescType theProperty,
  356.                                      TList* theObjectsToSet,
  357.                                      // Caller must create this list. ISetPropertyCommand clones it so you can free it immediately.
  358.                                      TAppleEvent* message,
  359.                                      TAppleEvent* reply);
  360.  
  361.     virtual ~TSetPropertyCommand();
  362.  
  363.     virtual void DoIt();
  364.  
  365.     virtual void UndoIt();
  366.  
  367.     virtual void RedoIt();
  368. };
  369.  
  370. //----------------------------------------------------------------------------------------
  371. // TPropertyAccessor
  372. //----------------------------------------------------------------------------------------
  373.  
  374. class TPropertyAccessor : public TObject, public MScriptableObject
  375. {
  376.  
  377.     MA_DECLARE_CLASS;
  378.  
  379.     // When an object specifier describes a property of an object instead of the object itself,
  380.     // MScriptableObject:GetContainedObject will create a TPropertyAccessor.
  381.     // The TPropertyAccessor knows which property of which object are involved and can get and set the value.
  382.  
  383. public:
  384.     MScriptableObject* fWhichObject;                        // The object whose property we are concerned with.
  385.     DescType fWhichProperty;                    // The property we're going to get or set.
  386.  
  387.     TPropertyAccessor();
  388.         // Empty constructor to satisfy compiler.
  389.     virtual ~TPropertyAccessor();
  390.         // Destructor
  391.  
  392.     virtual void IPropertyAccessor(MScriptableObject* whichObject,
  393.                                    DescType whichProperty);
  394.     
  395.     virtual TCommandHandler* GetCommandContext(const CommandNumber aCommandNumber) const;
  396.     
  397.     virtual void DoScriptCommand(CommandNumber    aCommandNumber,
  398.                                 TAppleEvent*     message,
  399.                                  TAppleEvent*     reply);
  400.         // Handles GetData and SetData events.
  401.  
  402.     virtual Boolean CompareScriptableObjects(DescType operation,
  403.                                              const CAEDesc& thingToCompare);
  404.         // Compares the values of the two properties.
  405.  
  406.     virtual void SetObjectProperty(const CAEDesc& thePropertyValue,
  407.                                     DescType whichProperty);
  408.         // Calls SetObjectProperty for its object.
  409.  
  410.     virtual void DoAEGetDataSize(TAppleEvent* message,
  411.                                  TAppleEvent* reply);
  412.         // Returns the data size for its property.
  413.  
  414.     virtual Boolean GetObjectProperty(CAEDesc& thePropertyValue,
  415.                                       DescType whichProperty,
  416.                                       const CAEDesc& desiredType);
  417.         // Calls GetObjectProperty for its object.
  418.  
  419. #if qAttachable
  420.     virtual Boolean HandleOSAEvent(CommandNumber     aCommandNumber,
  421.                                     TAppleEvent*     message,
  422.                                     TAppleEvent*     reply);
  423. #endif
  424. };
  425.  
  426. //----------------------------------------------------------------------------------------
  427. // TSetPropertyEvent
  428. //----------------------------------------------------------------------------------------
  429.  
  430. class TSetPropertyEvent : public TAppleEvent
  431. {
  432.  
  433.     MA_DECLARE_CLASS;
  434.  
  435.     // This is a variation on TAppleEvent that handles the overhead in creating an
  436.     // event used to change an object's property. When you want to send yourself
  437.     // an Apple Event to set a property, use one of these.
  438.  
  439. public:
  440.  
  441.     TSetPropertyEvent();
  442.     virtual ~TSetPropertyEvent();
  443.         // Destructor
  444.  
  445.     virtual void ISetPropertyEvent(const CAEDesc& itsAddress,
  446.                                    long itsSendingMode,
  447.                                    MScriptableObject* objectToSet,
  448.                                    DescType propType);
  449.         // Initializes the event with the recipient, sending mode, the object you want to set and the 
  450.         // property you want to modify. Creates an object specifier for the object's property and 
  451.         // sticks it in the direct object.
  452. };
  453.  
  454. //----------------------------------------------------------------------------------------
  455. // TMenuAccessor
  456. //----------------------------------------------------------------------------------------
  457.  
  458. class TMenuAccessor : public TObject, public MScriptableObject
  459. {
  460.  
  461.     MA_DECLARE_CLASS;
  462.  
  463.     // When an object specifier describes a menu, TApplication:GetContainedObject will
  464.     // create a TMenuAccessor.
  465.     // The TMenuAccessor knows which menu is targeted and can act on events directed at the menu.
  466.  
  467. public:
  468.     MenuRef fMenu;        // The menu we handle events for.
  469.     short fIndex;            // Index of the menu in the displayed menu bar.
  470.  
  471.     TMenuAccessor();
  472.     virtual ~TMenuAccessor();
  473.         // Destructor
  474.  
  475.     virtual void IMenuAccessor(MenuRef theMenu, short theIndex);
  476.     
  477.     virtual Boolean GetObjectProperty(CAEDesc& thePropertyValue,
  478.                                       DescType whichProperty,
  479.                                       const CAEDesc& desiredType);
  480.         // Returns properties for the menu.
  481.  
  482.     virtual MScriptableObject* GetIndContainedObject(DescType desiredType,
  483.                                                        long index);
  484.         // Returns a menu item contained within a menu.
  485.  
  486.     virtual long CountContainedObjects(DescType desiredType);
  487.         // Returns the number of menu item in a menu.
  488.  
  489.     virtual void SetObjectProperty(const CAEDesc& thePropertyValue,
  490.                                    DescType whichProperty);
  491. };
  492.  
  493. //----------------------------------------------------------------------------------------
  494. // TMenuItemAccessor
  495. //----------------------------------------------------------------------------------------
  496.  
  497. class TMenuItemAccessor : public TObject, public MScriptableObject
  498. {
  499.  
  500.     MA_DECLARE_CLASS;
  501.  
  502.     // When an object specifier describes a menuitem, TMenuAccessor:GetContainedObject will
  503.     // create a TMenuItemAccessor.
  504.     // The TMenuItemAccessor knows which item is targeted and can act on events
  505.     // directed at that item.
  506.  
  507. public:
  508.     MenuRef fMenu;        // The menu the item is in.
  509.     short fMenuItem;        // Index of the menu item.
  510.  
  511.     TMenuItemAccessor();
  512.     virtual ~TMenuItemAccessor();
  513.         // Destructor
  514.  
  515.     virtual void IMenuItemAccessor(MenuRef theMenu, short theItem);
  516.     
  517.     virtual Boolean GetObjectProperty(CAEDesc& thePropertyValue,
  518.                                       DescType whichProperty,
  519.                                       const CAEDesc& desiredType);
  520.         // Returns properties for the menu item.
  521.  
  522.     virtual void DoAEOpen(TAppleEvent* message, TAppleEvent* reply);
  523.         // Simulates choosing the menu item
  524.  
  525.     virtual void SetObjectProperty(const CAEDesc& thePropertyValue,
  526.                                    DescType whichProperty);
  527. };
  528.  
  529. //------------------------------------------------------------------------------------
  530. // TOSADispatcher Inlines
  531. //------------------------------------------------------------------------------------
  532.  
  533. inline void TOSADispatcher::SetDefaultTarget(MDefaultScriptableObject* defaultTarget)
  534. {
  535.     fDefaultTarget = defaultTarget;
  536. };
  537.     
  538. inline MDefaultScriptableObject* TOSADispatcher::GetDefaultTarget()
  539. {
  540.     return fDefaultTarget;
  541. };
  542.  
  543. inline void TOSADispatcher::SetAEResolveFlags(const short newFlags)
  544. {
  545.     fAEResolveFlags = newFlags;
  546. };
  547.  
  548. //------------------------------------------------------------------------------------
  549. // Global Functions
  550. //------------------------------------------------------------------------------------
  551.  
  552. // Initialize the scripting unit. Call this function to create a global
  553. // instance of TScriptEventDispatcher, and to install events supported in
  554. // Apple Event dispatch table resources. 
  555.  
  556. inline void InitUScripting()
  557. {
  558.     MA_REGISTER_CLASS(TOSADispatcher);
  559.     TOSADispatcher::InitUScripting(&TOSADispatcher::fgClassDesc);
  560. }
  561.  
  562. //    To initialize scripting with a custom scripting dispatcher, use
  563. //    some code like this: 
  564. //
  565. //        MA_REGISTER_CLASS(TMyCustomOSADispatcher);
  566. //        TMyCustomOSADispatcher::InitUScripting(&TMyCustomOSADispatcher::fgClassDesc);
  567.  
  568. #endif // __USCRIPTING__
  569.